Actually there is a thing I forgot to tell you guys.

To create with the spactaQL tool, we need to change one of Query/Mutation/Subscriptions to parent type.
You can see this commit.
The reason why we need to do this, I think the graphql/validation/validate.js library in spectaql couldn't generate with no-parent type of Query/Mutation/Subscription SDL files.

Do you guys think this method seems fine?

@suyeon-jung-dev Here are a couple of things we should add:

• A window to try the API for a given server URL (similar to Swagger).
• Provide examples of success and failure cases while documenting them.

LMK if this sounds good?

Hi, @neelanjan00 . If we need to add these two things, I'll look for other tools. Because SpectaQL doesn't support them.

• A window to try the API for a given server URL (similar to Swagger).
  SpectaQL supports only api end point paths like below.

• Provide examples of success and failure cases while documenting them
  SpectaQL supports only success case.

Thank you for your feedback :)

Can you please check if you can find any tool that can help us achieve this? This will be very useful! Thanks!

@suyeon-jung-dev Here are a couple of things we should add:

• A window to try the API for a given server URL (similar to Swagger).
• Provide examples of success and failure cases while documenting them.

LMK if this sounds good?

Hi @neelanjan00

I looked into the two things you asked about earlier, but I couldn't find any tools that have all the features we need. 🥲

The tool we previously used, dociql, is no longer being updated — its last update was 2 years ago. Additionally, dociql can only be installed in a Python 2 environment. Even if we were to continue using it, we would still need to create a config.yaml file manually, which requires typing out every line.

Regarding the feature "A window to try the API for a given server URL (similar to Swagger)," I have some concerns about potential security issues. We can also use GraphQL Playground for this purpose instead.

Considering all of this, I think SpectaQL is the best option.

@suyeon-jung-dev Here are a couple of things we should add:

• A window to try the API for a given server URL (similar to Swagger).
• Provide examples of success and failure cases while documenting them.

LMK if this sounds good?

Hi @neelanjan00

I looked into the two things you asked about earlier, but I couldn't find any tools that have all the features we need. 🥲

The tool we previously used, dociql, is no longer being updated — its last update was 2 years ago. Additionally, dociql can only be installed in a Python 2 environment. Even if we were to continue using it, we would still need to create a config.yaml file manually, which requires typing out every line.

Regarding the feature "A window to try the API for a given server URL (similar to Swagger)," I have some concerns about potential security issues. We can also use GraphQL Playground for this purpose instead.

Considering all of this, I think SpectaQL is the best option.

Okay sure, I guess we can just document the various success and failure cases for each API. We can skip the Swagger-like interface in favour of the in-built GraphQL playground.

Okay sure, I guess we can just document the various success and failure cases for each API. We can skip the Swagger-like interface in favour of the in-built GraphQL playground.

Hi @neelanjan00 , I tried to find many alternatives, but it seems unnecessary to create an error/success cases for every single request. (we already have success cases)

1. All open source that auto-generates GraphQL docs (DociQL, MagiDoc, SpectaQL...) make docs based on 'schema'.

In the case of an error, it depends on implementing the resolver function (not schema), so we have to check it manually to add it to the API docs for the error case. (It's time time-consuming job and hard to maintain)

2. Unlike REST API, GraphQL returns 200 OKs even in case of an error

All GraphQL queries and mutations return errors in a structure like List. In our codebase, we only return a single error. It also differs only in the message part of the error and does not return any other metadata or data.

• error Schema example (https://graphql.org/learn/validation/)
• multiple errors (https://gqlgen.com/reference/errors/#multiple-errors)

IMO, it would be much more efficient to add a page for common errors. This is because most errors coming from GraphQL servers are similar(authentication failure, MongoDB CRUD failure, etc.). SpectaQL supports adding pages using Markdown. So how about using this feature?

Okay sure, I guess we can just document the various success and failure cases for each API. We can skip the Swagger-like interface in favour of the in-built GraphQL playground.

Hi @neelanjan00 , I tried to find many alternatives, but it seems unnecessary to create an error/success cases for every single request. (we already have success cases)

1. All open source that auto-generates GraphQL docs (DociQL, MagiDoc, SpectaQL...) make docs based on 'schema'.

In the case of an error, it depends on implementing the resolver function (not schema), so we have to check it manually to add it to the API docs for the error case. (It's time time-consuming job and hard to maintain)

2. Unlike REST API, GraphQL returns 200 OKs even in case of an error

All GraphQL queries and mutations return errors in a structure like List. In our codebase, we only return a single error. It also differs only in the message part of the error and does not return any other metadata or data.

• error Schema example (https://graphql.org/learn/validation/)
• multiple errors (https://gqlgen.com/reference/errors/#multiple-errors)

IMO, it would be much more efficient to add a page for common errors. This is because most errors coming from GraphQL servers are similar(authentication failure, MongoDB CRUD failure, etc.). SpectaQL supports adding pages using Markdown. So how about using this feature?

Sounds good, this is what I meant as well actually, sorry for the confusion if any. Yes, having some sort of documentation around the success and most common failure messages for at least the most common mutations and queries will be a good way forward.

I deployed a demo using the branch feature/update-api-docs-3.9.1-deploy-test on my repository.

You can check 3.9.x, 3.10.x, 3.11.x version of GraphQL docs demo with those links.

Finally, the changes I made include:

1. Replacing the GraphQL docs dociql with spectaql
2. Updating GraphQL docs v3.9.x and higher (3.9.x, 3.10.x, 3.11.x)
3. Adding common error response information
4. Update the latest version of GraphQL docs URL (v3.11.x) on Litmus Documentation Page (/litmus/experiments/api/contents)

[Common Error Response page demo]